home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / shells / kiss-0.11 / kiss-0 / kiss / doc / technotes.txt next >
Text File  |  1995-04-19  |  7KB  |  171 lines
  1.  
  2.             K I S S  Technical notes
  3.  
  4.  
  5. Compiling Kiss
  6. --------------
  7.  
  8. There are basically three versions of Kiss: (a) one that includes readline
  9. support, (b) one that includes getline, and (b) one that contains neither. The
  10. versions are appropriately named "rkiss" (for readline), "gkiss" (for getline)
  11. and "bkiss" (for bare). The biggest executable is of course rkiss, since it
  12. includes editing and filename completion; the smallest is bkiss.
  13.  
  14. I guess that for a SAR disk (see my Search-And-Rescue disk package on
  15. ftp.icce.rug.nl:/pub/unix/SAR*), you'd use the `getline' version or even the
  16. `bare' version; for reasons of space.
  17.  
  18. Important note: All three versions are linked by the Makefile to use shared
  19. libraries. They are especially menat for SAR disks, where you have the libs
  20. anyway. If you want to make a Kiss for usage on your HDU (in emergencies, when
  21. the libs disappear or whatever), modify the Makefile to link with the
  22. `-static' flag and re-make.
  23.  
  24. To compile:
  25.  
  26.     a. Edit the Makefile and adjust the macros at the top. If you have the
  27.        readline libs, where do they reside? What is your BINDIR if you
  28.        want to install the progs?
  29.     b. Type "make rkiss" (readline), "make gkiss" (getline) or
  30.        "make bkiss" (bare version). The executable file will then be "rkiss"
  31.        or "gkiss" or "bkiss". Or just type "make all" to make all three.
  32.     c. "make rinstall" will "make rkiss" and install it to $(BINDIR) (defined
  33.        in the Makefile); "make binstall" will do the same for the bare
  34.        version. A "make ginstall" will make gkiss and install it.
  35.  
  36. You will need the following for a successful installation:
  37.     - gcc better than 2.5.8
  38.     - libs 4.6.27 or better
  39.     - libreadline.a and libtermcap.a if you want to make the readline version
  40.     - bison and flex.
  41.  
  42. You won't need the getline sources, I've included them in the archive of the
  43. sources (though I am not the author neither the maintainer).
  44.  
  45.  
  46. When you change the sources
  47. ---------------------------
  48.  
  49. When you change the sources, please adher to the following:
  50.  
  51.     a. Always inform me if you have useful additions! Mail me at
  52.        karel@icce.rug.nl. I'd like to have the latest version too! Also
  53.        describe what you've changed, and why you've changed it -- instead of
  54.        just mailing me some diffs.
  55.  
  56.     b. Edit the file "subversion.h" (read that as sub-version, not as
  57.        revolution) and increment the number there. That will hopefully keep
  58.        track of compilations. The versions are displayed with Kiss' "ver"
  59.        command.
  60.     
  61.  
  62. Adding a built-in command
  63. -------------------------
  64.  
  65. This section describes how to create a built-in command, say "tar" (not that
  66. you would want to do that.. but whatever). Before you decide that you need it,
  67. please consider:
  68.  
  69.     a. Built-ins should be what you expect everyone to need in a rescue-disk
  70.        environment. E.g., "ls". But not "loadkeys".
  71.  
  72.     b. Beware of promoting hardware-dependant stuff to built-ins. E.g.,
  73.        "e2fsck" may be what everyone uses, but I don't think that it should be
  74.        a built-in command.
  75.  
  76.  
  77. 1. Making the command known to Kiss.
  78.  
  79.     Edit kiss.h and add a function declaration to the list of external
  80.     functions. E.g., if you implement the "tar" command, then add a line
  81.  
  82.         extern int dotar (Stringstack s);
  83.  
  84.     to kiss.h. The function must return an integer (exit status) and must
  85.     expect a Stringstack as its only argument. We'll get to Stringstacks
  86.     later. Hint: enter the function name in alphabetical order, somewhere
  87.     between the other doxxxx() declarations.
  88.  
  89.     Next, edit kiss.c and add to the table at the top:
  90.  
  91.         { "tar",    dotar,        0 },
  92.  
  93.     This table is used by the parser: when the string "tar" is seen, then
  94.     dotar() will be called. The last field (0) means that dotar() can be
  95.     called by a forked-off child process. A 1 in the last field means that the
  96.     command is a `level zero' command, e.g., "setenv" is such a command: it
  97.     must be handled by the parent Kiss and not by a child process. Generally,
  98.     the built-in commands can be handled by children.
  99.  
  100.     Now edit dohelp.c (the "help" command) and add the description of your
  101.     command to the list. It will then be shown when someone requests "help".
  102.  
  103.     Finally, edit the Makefile and add dotar.o to the list of objects.
  104.  
  105.  
  106. 2. Implementing your function.
  107.  
  108.     I strongly suggest that you implement your function dotar() in a file
  109.     dotar.c (hence the name dotar.o added to the Makefile). That helps keeping
  110.     the overview over what's where.
  111.  
  112.     Here's the start of your function, comments illustrate arguments etcetera:
  113.  
  114.     #include "kiss.h"    /* all includes are in kiss.h, no need to 
  115.                    request stdio.h etc. too */
  116.  
  117.     int dotar (Stringstack s)
  118.     /* function is called: dotar
  119.        returns: an int (exit status), 0 if all is ok
  120.        expects: a Stringstack, which holds two fields:
  121.             nstr : number of stored strings (`argc' like counter)
  122.             str  : array of strings        (`argv' like list)
  123.         */
  124.     {
  125.         /* now for some options parsing, e.g. -c -v -z -f
  126.            will be recognized; also -h for help */
  127.  
  128.         register int
  129.         opt;
  130.  
  131.         while ( (opt = getopt (s.nstr, s.str, "cvzfh")) != -1 )
  132.         switch (opt)
  133.         {
  134.             case 'v':
  135.             ....
  136.             break;
  137.             ...
  138.             case 'h':
  139.             default:
  140.             error ("Bad commandline.\n"
  141.                    "Usage: %s [-cvzf] archive [file(s)]\n",
  142.                    progname);
  143.                 }                    
  144.     ....
  145.     }
  146.  
  147.  
  148.     Implementation comments:
  149.  
  150.     - char *progname holds the `bare' program name, in your case "tar".
  151.       Use it in printf()'s or whatever. Using the actual invocation name
  152.       is better than hardwiring "tar" or whatever name; e.g., if you
  153.       change the command name to "mytar" in kiss.c then "mytar" will show
  154.       up as "progname" in your displayed messages.
  155.     - s.nstr and s.str hold the arguments, like argc/argv
  156.     - Use getopt() and optind to parse the flag arguments. See the
  157.       manpages. Always enable a `-h' flag, which with the `default' case,
  158.       shows help.
  159.     - Use the function error() to show error messages and terminate; it
  160.       works just like printf() but prints "program: " first.
  161.     - Use warning() to show warnings, works like error() but doesn't
  162.       terminate.
  163.  
  164.     If you need auxiliary functions to your dotar() function, you can either
  165.     make them statics in dotar.c or declare them in kiss.h and implement them
  166.     in separate source files. In the latter case you'd of course need to add
  167.     the names of those files to the Makefile.
  168.     
  169. If you want to see a small example, check out dotouch.c which implements the
  170. "touch" command. It's about the smallest thing that I can think of.
  171.